Aminet 2

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 2 / Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso / Aminet / dev / misc / ImageFXDevKit.lha / sdev / doc / Scan.autodoc < prev

Wrap

Text File | 1993-06-30 | 55.2 KB | 2,243 lines

TABLE OF CONTENTS scan.library/AllocBuffer scan.library/AllocChipBitMap scan.library/AllocFastBitMap scan.library/ArrangePanel scan.library/Bar scan.library/BClose scan.library/BeginBar scan.library/BFlush scan.library/BGetc scan.library/BGets scan.library/BOpen scan.library/BPutc scan.library/BPuts scan.library/BRead scan.library/BSeek scan.library/BWrite scan.library/ClearBitMap scan.library/CloseWindowSafely scan.library/DeleteBitMap scan.library/EasyProcess scan.library/EndBar scan.library/Error scan.library/FreeBuffer scan.library/GetBufLine scan.library/GetBufLines scan.library/GetError scan.library/HidePanel scan.library/InitBuffer scan.library/IntegerRequest scan.library/IsAnimation scan.library/KillBuffer scan.library/mixer scan.library/NewGetFile scan.library/NumberRequest scan.library/ObtainBuffer scan.library/ParseCommand scan.library/PutBufLine scan.library/PutBufLines scan.library/PutNewBufLine scan.library/ReadBuffer scan.library/RedrawArea scan.library/RedrawFull scan.library/ReleaseBuffer scan.library/ReplaceBuffer scan.library/SaveBrush scan.library/SaveMapped scan.library/SaveUndo scan.library/SetError scan.library/ShowPanel scan.library/ShowStatus scan.library/StringRequest scan.library/TogglePanel scan.library/VBoolRequest scan.library/VErrorf scan.library/VInfoRequest scan.library/zzzzzz scan.library/AllocBuffer NAME AllocBuffer - Allocate and initialize a Buffer structure. SYNOPSIS buffer = AllocBuffer ( name, width, height, depth, bits, flags ); D0.L A0 D0.W D1.W D2.W D3.W D4.W struct Buffer *AllocBuffer ( char *, short, short, short, short, short ); FUNCTION Allocate a Buffer structure, complete with image data planes. Initializes the structure to suitable default values. INPUTS name -- Name of buffer. Currently ignored. Use NULL. width -- Width of buffer in pixels. height -- Height of buffer in pixels. depth -- Depth of buffer in 8-bit planes, use 1 for a greyscale buffer or 3 for a color buffer. bits -- Number of bits per plane. Always use 8. flags -- Flag bits. Set one or more of the following: BUFF_DISK - force buffer to be created on disk. (use only if you know what you're doing.) BUFF_BRUSH - buffer is really a brush. (rarely, if ever, needed.) BUFF_NOVMEM - should not use virtual memory for the buffer. (try to avoid this one.) More often than not, you will simply want to use a flags value of 0. If the buffer is too large to fit in memory, the user will be asked if he wants to use virtual memory, in which case the buffer will be created on disk anyway. RESULT buffer --- Pointer to a properly filled-in Buffer structure, with allocated image data space. NULL on failure, with a secondary result code set in the global error. EXAMPLE NOTES DO NOT ASSUME THE IMAGE DATA IS CLEARED!! BUGS SEE ALSO scan.library/KillBuffer,scan/buf.h scan.library/AllocChipBitMap scan.library/AllocChipBitMap NAME AllocChipBitMap -- Allocate a bitmap from chip memory. SYNOPSIS bitmap = AllocChipBitMap ( width, height, depth ); D0.L D0.L D1.L D2.L struct BitMap *AllocChipBitMap ( int, int, int ); FUNCTION Allocate a BitMap structure and bitplanes from chip memory, suitable for use on an Amiga display. The bitplanes are cleared. INPUTS width -- Width of the bitmap in pixels. height -- Height of the bitmap in pixels. depth -- Depth of bitmap in planes. RESULTS bitmap -- Pointer to an initialized BitMap structure, ready for use. EXAMPLE NOTES Uses the new graphics.library AllocBitMap() function under V39. BUGS SEE ALSO scan.library/AllocFastBitMap,scan.library/DeleteBitMap scan.library/AllocFastBitMap scan.library/AllocFastBitMap NAME AllocFastBitMap -- Allocate a bitmap from fast memory. SYNOPSIS bitmap = AllocFastBitMap ( width, height, depth ); D0.L D0.L D1.L D2.L struct BitMap *AllocFastBitMap ( int, int, int ); FUNCTION Allocate a BitMap structure and bitplanes from fast memory. The bitplanes are cleared. INPUTS width -- Width of the bitmap in pixels. height -- Height of the bitmap in pixels. depth -- Depth of bitmap in planes. RESULTS bitmap -- Pointer to an initialized BitMap structure, ready for use. EXAMPLE NOTES Uses the new graphics.library AllocBitMap() function under V39. BUGS SEE ALSO scan.library/AllocFastBitMap,scan.library/DeleteBitMap scan.library/ArrangePanel scan.library/ArrangePanel NAME ArrangePanel -- Arrange the ImageFX screens properly. SYNOPSIS ArrangePanel () void ArrangePanel ( void ); FUNCTION Arrange all of the screens that ImageFX uses such that they are displayed properly. Normally one would call this function right after opening a screen of your own, so that the menu and possibly the palette screens are shown over the bottom properly. You should always call this function instead of doing it yourself, for various reasons. Note however, that under V39, any screens you open yourself will always appear in front of all ImageFX screens, unless you take steps to attach the new screen to the ImageFX screens, like this: YourScreen = OpenScreenTags(NULL, SA_Parent, ScanBase->sb_vScreen, .... TAG_END); ArrangePanel(); INPUTS None. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/Bar NAME Bar - Increment status bar display. SYNOPSIS cancelled = Bar ( iteration ); D0.L D0.L int Bar ( int ); FUNCTION Calculates the status bar scale to show the given iteration count. INPUTS iteration -- The current iteration of the operation. For example, while loading a file you would call Bar() for each scanline and pass the line number. RESULT cancelled -- If you specified that there should be a Cancel gadget with the BeginBar() function, then if the user clicks that Cancel you will get a non-zero result from Bar(). Otherwise, a zero result means to continue the operation. EXAMPLE BeginBar ("Chugging", 57, TRUE); for (i = 0; i < 57; i++) { if (Bar(i)) { Errorf ("You dope, you cancelled me!"); break; } /* perform some calculation here */ } EndBar(NULL); NOTES BUGS SEE ALSO scan.library/BeginBar,scan.library/EndBar scan.library/BClose scan.library/BClose NAME BClose -- Close a buffered file. SYNOPSIS BClose ( handle ); A0 void BClose ( struct BIO * ); FUNCTION Closes a buffered file previously opened with BOpen. INPUTS handle -- file handle as returned by BOpen. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/BOpen scan.library/BeginBar NAME BeginBar - Start a status bar operation. SYNOPSIS BeginBar ( title, maxvalue, abortable ); A0 D0.L D1.L void BeginBar (char *, int, BOOL) FUNCTION Initializes the status bar in preparation for a long operation. Also displays the busy pointer, and prevents the user from selecting gadgets on the menu panel. Note that you MUST call EndBar() to get back to normal operations; if you exit without calling EndBar(), the user will not be able to do anything as all the gadget input will be locked. INPUTS title -- The title to display for the operation. This should be kepts as short as possible (10 characters or so), as there is not a lot of room to display this. maxvalue -- The total number of iterations expected in the operation. For example, if you were loading a file you would place the expected number of rows here. abortable -- If TRUE, a Cancel gadget will be presented to the user. Otherwise, the operation is non-stoppable. RESULT None. EXAMPLE See scan.library/Bar. NOTES BUGS SEE ALSO scan.library/Bar,scan.library/EndBar scan.library/BFlush scan.library/BFlush NAME BFlush -- Flush current buffer to disk. SYNOPSIS BFlush ( handle ); A0 void BFlush ( struct BIO * ); FUNCTION For a MODE_NEWFILE buffered file, flush the contents of the buffer to disk. For a read file, this function does nothing. INPUTS handle -- file handle as returned by BOpen. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/BGetc scan.library/BGetc NAME BGetc -- Read a character from buffered file. SYNOPSIS character = BGetc ( handle ); D0.L A0 int BGetc ( struct BIO * ); FUNCTION Read the next available character from the given buffered file. The file handle must have been opened by BOpen as MODE_OLDFILE. INPUTS handle -- file handle as returned by BOpen. RESULTS character -- character that was read, or -1 on failure (eg. disk error). EXAMPLE NOTES BUGS SEE ALSO scan.library/BGets scan.library/BGets NAME BGets -- Read a string from a buffered file. SYNOPSIS count = BGets ( handle, buffer, maxlength ); D0.L A0 A1 D0.L int BGets ( struct BIO *, UBYTE *, int ); FUNCTION Read from the given buffered file until the next newline. The newline is NOT stripped. The file handle must have been opened by BOpen as MODE_OLDFILE. INPUTS handle -- file handle as returned by BOpen. buffer -- buffer into which to read the characters. maxlength -- maximum number of characters to read. RESULTS count -- number of characters actually read. EXAMPLE NOTES BUGS SEE ALSO scan.library/BOpen scan.library/BOpen NAME BOpen -- Open a file for buffered reading or writing. SYNOPSIS handle = BOpen ( filename, accessmode, bufsize ); D0.L A0 D0.L D1.L struct BIO *BOpen ( char *, ULONG, ULONG ); FUNCTION Open a file for buffered access. INPUTS filename -- name of file to open. accessmode -- MODE_OLDFILE for reading or MODE_NEWFILE for writing. bufsize -- size of buffer for reading or writing. If 0, then a default value will be used. RESULTS handle -- handle for subsequent access. Do not attempt to examine the contents of this structure. EXAMPLE NOTES BUGS SEE ALSO scan.library/BClose scan.library/BPutc scan.library/BPutc NAME BPutc -- Write a character to buffered file. SYNOPSIS success = BPutc ( handle, character ); D0.L A0 D0.B FUNCTION Write a single (unsigned) character to the given buffered file. The file handle must have been opened by BOpen as MODE_NEWFILE. INPUTS handle -- file handle as returned by BOpen. character -- byte to write to the file. RESULTS success -- TRUE if the character was sucessfully written, or FALSE if something went wrong (eg. disk error). EXAMPLE NOTES BUGS SEE ALSO scan.library/BPuts scan.library/BPuts NAME BPuts -- Write a string to a buffered file. SYNOPSIS success = BPuts ( handle, string ); D0.L A0 A1 BOOL BPuts ( struct BIO *, UBYTE * ); FUNCTION Write a null-terminated string to the given buffered file. The file handle must have been opened by BOpen as MODE_NEWFILE. A newline will be appended to the string when written to the file. INPUTS handle -- file handle as returned by BOpen. string -- null-terminated string to write to the file. A newline will be appended. RESULTS success -- TRUE if the string was sucessfully written, or FALSE if something went wrong (eg. disk error). EXAMPLE NOTES BUGS SEE ALSO scan.library/BRead scan.library/BRead NAME BRead -- Read a block of characters from a buffered file. SYNOPSIS count = BRead ( handle, buffer, length ); D0.L A0 A1 D0.L int BRead ( struct BIO *, UBYTE *, int ); FUNCTION Read a fixed number of characters from a buffered file. The file handle must have been opened by BOpen as MODE_OLDFILE. INPUTS handle -- file handle as returned by BOpen. buffer -- pointer to where to store read characters. length -- number of characters to read. RESULTS count -- number of characters actually read from the file, or -1 on failure (eg. disk error). EXAMPLE NOTES BUGS SEE ALSO scan.library/BSeek scan.library/BSeek NAME BSeek -- Seek to a file position within a buffered file. SYNOPSIS oldposition = BSeek ( handle, offset, from ); D0.L A0 D0.L D1.L int BSeek ( struct BIO *, int, int ); FUNCTION Seek to a specific file position in a way compatible with buffered files. INPUTS handle -- file handle as returned by BOpen. offset -- new file position. from -- where to seek from, OFFSET_BEGINNING, OFFSET_CURRENT, or OFFSET_END. RESULTS oldposition -- previous file position. EXAMPLE NOTES BUGS SEE ALSO scan.library/BWrite scan.library/BWrite NAME BWrite -- Write a block of characters to a buffered file. SYNOPSIS count = BWrite ( handle, buffer, length ); D0.L A0 A1 D0.L int BWrite ( struct BIO *, UBYTE *, int ); FUNCTION Write a fixed number of characters to a buffered file. The file handle must have been opened by BOpen as MODE_NEWFILE. INPUTS handle -- file handle as returned by BOpen. buffer -- pointer to characters to write. length -- number of characters to write. RESULTS count -- number of characters actually written to the file, or -1 on failure (eg. disk error). EXAMPLE NOTES BUGS SEE ALSO scan.library/ClearBitMap scan.library/ClearBitMap NAME ClearBitMap -- Clear the contents of a BitMap. SYNOPSIS ClearBitMap ( bitmap ); A0 void ClearBitMap ( struct BitMap * ); FUNCTION Clears the bitplane memory of the given bitmap. The bitplanes may be in chip memory or fast memory. INPUTS bitmap -- pointer to a BitMap structure. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/CloseWindowSafely scan.library/CloseWindowSafely NAME CloseWindowSafely -- Safely close a shared IDCMP window. SYNOPSIS CloseWindowSafely ( window ); A0 void CloseWindowSafely ( struct Window *window ); FUNCTION If you open a window that share's ImageFX main IDCMP, you should use this function to close the window or else risk fireworks. INPUTS window -- pointer to Window to close. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/DeleteBitMap scan.library/DeleteBitMap NAME DeleteBitMap -- Deallocate a bitmap structure. SYNOPSIS DeleteBitMap ( bitmap ); A0 void DeleteBitMap ( struct BitMap * ); FUNCTION Frees the bitplane memory and BitMap structure of the given bitmap. Dimensions of the bitmap are obtained from the BitMap structure itself. Only use this function on BitMaps obtained with the AllocChipBitMap() or AllocFastBitMap() functions. INPUTS bitmap -- pointer to BitMap to free. RESULTS None. EXAMPLE NOTES Uses the new graphics.library FreeBitMap() function under V39. BUGS SEE ALSO scan.library/EasyProcess scan.library/EasyProcess NAME EasyProcess -- Perform a simple 1:1 effect on an ImageFX buffer. SYNOPSIS success = EasyProcess ( title, color_callback, grey_callback ); D0.L A0 A1 A2 BOOL EasyProcess ( char *, void (*color_callback)(), void (*grey_callback)() ); FUNCTION Perform a simple affect on the user's currently selected region (main buffer, brush, or region thereof). Regional information, feathering, and other factors will affect the operation. You should try to use this function if possible, as it does a great deal of work for you. INPUTS title -- title to place in status bar while in progress. color_callback -- callback function which actually modifies color pixels. It's prototype is: void color_callback (UBYTE *redptr, UBYTE *grnptr, UBYTE *bluptr, short x, short y); Where: redptr -- pointer to current red pixel to be modified. grnptr -- pointer to current green pixel to be modified. bluptr -- pointer to current blue pixel to be modified. x -- current horizontal pixel location. y -- current vertical pixel location. grey_callback -- callback function which actually modifies grey pixels. It's prototype is: void grey_callback (UBYTE *greyptr, short x, short y); Where: greyptr -- pointer to current grey pixel to be modified. x -- current horizontal pixel location. y -- current vertical pixel location. Arguments are passed on the stack. You must make sure to restore A4 in your callback functions if you are using small data model! EasyProcess() will decide whether to use the color or greyscale callback function, based on the image it is working on. RESULTS success -- TRUE if the process was successful, FALSE on failure. EXAMPLE /* A simple color negative effect */ void __saveds colorback (UBYTE *r, UBYTE *g, UBYTE *b, short x, short y) { *r = 255 - *r; *g = 255 - *g; *b = 255 - *b; } void __saveds greyback (UBYTE *g, short x, short y) { *g = 255 - *g; } void DoEffect (void) { EasyProcess("Negative", colorback, greyback); } NOTES This should not be used to do geometric or translational effects on a buffer (ie. where pixel positions are moved). This is only good for doing simple color effects. BUGS SEE ALSO scan.library/EndBar NAME EndBar - End a status bar operation. SYNOPSIS EndBar ( dummy ); void EndBar (void *); FUNCTION This cleans up and ends a status bar operation. It clears the busy pointer and allows the user to select gadgets in the menu panel again. INPUTS None, really. There used to be an argument, but it has been removed. You should pass NULL as the argument. RESULT None. EXAMPLE See scan.library/Bar. NOTES BUGS None known. SEE ALSO scan.library/BeginBar,scan.library/Bar scan.library/Error NAME Error - Show error message for last generated error. SYNOPSIS Error (); void Error ( void ); FUNCTION Will display a requester to the user showing the text for the last error generated. This function does not return until the user clicks Okay. INPUTS None. RESULT None. EXAMPLE buffer = AllocBuffer (NULL, 320, 200, 1, 8, 0); if (buffer == NULL) { /* can't get buffer? */ Error(); /* tell what happend */ return; } NOTES BUGS SEE ALSO scan.library/Errorf,scan.library/SetError scan.library/FreeBuffer scan.library/FreeBuffer NAME FreeBuffer -- Free ImageFX's main buffer. SYNOPSIS FreeBuffer (); void FreeBuffer ( void ); FUNCTION Frees the current main buffer, by calling KillBuffer(). INPUTS None. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/GetBufLine NAME GetBufLine - Get pointer(s) to a Buffer scanline. SYNOPSIS success = GetBufLine ( buffer, redptr, grnptr, bluptr, row ); D0.L A0 A1 A2 A3 D0.W int GetBufLine ( struct Buffer *, UBYTE **, UBYTE **, UBYTE **, short ); FUNCTION Fills in the supplied pointers with pointers to the image data for a Buffer. You should ONLY reference a buffer by using this function, as there is more work than meets the eye for a buffer maintained on disk. INPUTS buffer -- Pointer to a Buffer obtained via. ObtainBuffer(). redptr -- Where to store Red scanline pointer. grnptr -- Where to store Green scanline pointer. bluptr -- Where to store Blue scanline pointer. row -- Which scanline to retreive, starting from 0 at the topmost scanline. RESULT success -- Non-zero if the command was successful. It can only fail if the buffer is maintained on disk and enough memory cannot be allocated to read the scanline. A rare occurance, but one worth checking for. EXAMPLE NOTES For a greyscale buffer, "grnptr" and "bluptr" are set to point to the same data as "redptr". PAY ATTENTION TO THE RETURN VALUE!! Failing to gracefully handle a GetBufLine failure can cause serious problems. BUGS SEE ALSO scan.library/PutBufLine,scan.library/PutNewBufLine scan.library/GetBufLines scan.library/GetBufLines NAME GetBufLines -- Get multiple buffer scanlines at once. SYNOPSIS success = GetBufLines ( buffer, rptr, gptr, bptr, top, rows ); D0.L A0 A1 A2 A3 D0.L D1.L int GetBufLines ( struct Buffer *buffer, UBYTE **rptr, UBYTE **gptr, UBYTE **bptr, short top, short rows ); FUNCTION Fills in the supplied pointers with pointers to a "chunk" of an image, consisting of more than one scanline. This is handy for convolution-style operations. You should try to use this whenever possible when you need two or more adjacent scanlines, as it is somewhat faster than multiple GetBufLine()'s. INPUTS buffer -- Pointer to a Buffer obtained via. ObtainBuffer(). redptr -- Where to store Red scanline pointer. grnptr -- Where to store Green scanline pointer. bluptr -- Where to store Blue scanline pointer. top -- Topmost scanline to retreive, starting from 0 at the topmost scanline. rows -- Number of scanlines to retreive. RESULTS success -- non-zero if successful, or zero on failure. EXAMPLE NOTES It *is* possible to, for example, grab a topedge of -1 and a row count of 3 (ie. go out of bounds of the image), but the image data outside the area of the image will be undefined. BUGS SEE ALSO scan.library/GetError scan.library/GetError NAME GetError -- Retreive secondary error code. SYNOPSIS error = GetError (); D0.L ULONG GetError ( void ); FUNCTION Returns the current secondary error code, as set by a previous call to SetError(). INPUTS None. RESULTS error -- current error code. See "scan/errors.h". EXAMPLE NOTES BUGS SEE ALSO scan.library/HidePanel scan.library/HidePanel NAME HidePanel -- Push the menu screen to the back. SYNOPSIS HidePanel () void HidePanel (void); FUNCTION Pushes the menu screen ("panel") to the back, if it is not already hidden. INPUTS None. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/ShowPanel,scan.library/TogglePanel scan.library/InitBuffer scan.library/InitBuffer NAME InitBuffer -- Create ImageFX main buffer. SYNOPSIS InitBuffer ( name, width, height, depth, bits, flags ); A0 D0.W D1.W D2.W D3.W D4.W void InitBuffer ( char *, short, short, short, short, short ); FUNCTION Creates a main image buffer, deleting the old one first if it exists. This function is otherwise identical to AllocBuffer(). INPUTS See AllocBuffer(). RESULTS None. EXAMPLE NOTES You can tell whether the call was succesful or not by checking the result of GetError(), or by doing an ObtainBuffer(0). DO NOT ASSUME THE IMAGE DATA IS CLEARED!! BUGS SEE ALSO scan.library/IntegerRequest scan.library/IntegerRequest NAME IntegerRequest -- Present a slider gadget requester to the user. SYNOPSIS result = IntegerRequest ( title, low, high, initial ); D0.L A0 D0.L D1.L D2.L LONG IntegerRequest ( char *, LONG, LONG, LONG ); FUNCTION Display a requester containing a slider gadget to the user. The user must select a value or cancel before this function will return. INPUTS title -- Title of the requester. low -- Lowest value that can be selected with the slider. high -- Highest value that can be selected with the slider. initial -- Initial value of the slider. RESULTS result -- value selected by the user. If the value is less than the lowest possible value, then the user cancelled the requester. EXAMPLE value = IntegerRequest("Pick a number:", -10, 10, 0); if (value < -10) Errorf("Hey, you can't cancel me!"); NOTES BUGS SEE ALSO scan.library/IsAnimation scan.library/IsAnimation NAME IsAnimation -- Determine if a file is an animation (1.50). SYNOPSIS result = IsAnimation ( filename, format ); D0.L A0 A1 int IsAnimation ( char *filename, char *format ); FUNCTION Determine if an image file is an animation (has multiple frames) or not. First finds out the type of file, then returns whether that type of file is capable of multiple frames. INPUTS filename -- name of file to check. format -- NULL to make ImageFX determine the file format, or the name of a file format to force it to check that format. RESULTS result -- non-zero if the file is an animation, zero if it is not. EXAMPLE NOTES BUGS SEE ALSO scan.library/KillBuffer NAME KillBuffer - Deallocate a Buffer structure. SYNOPSIS KillBuffer ( buffer ); A0 void KillBuffer ( struct Buffer * ); FUNCTION Deallocates all the memory used in a Buffer structure, including image data memory, structure memory, and anything in between. The buffer no longer exists when this function returns. INPUTS buffer -- Pointer to a Buffer structure. RESULT None. EXAMPLE NOTES BUGS SEE ALSO scan.library/AllocBuffer,scan/buf.h scan.library/mixer scan.library/mixer NAME mixer -- Mix two color values. SYNOPSIS result = mixer ( oldvalue, newvalue, blend ); D0.W D0.W D1.W D2.W short mixer ( short oldvalue, short newvalue, short blend ); FUNCTION Mix two color values using a blend percentage. INPUTS oldvalue -- original value (0-255). newvalue -- new value to blend into the old value (0-255). blend -- blend value (0-255) ; higher blend values blend more of the new value into the old value. RESULTS result -- resulting value (0-255). EXAMPLE NOTES This function is handy for alpha channel blending style operations. BUGS None known. SEE ALSO scan.library/NewGetFile scan.library/NewGetFile NAME NewGetFile -- Open a file requester. SYNOPSIS file = NewGetFile ( fileinfo, title, flags ); D0.L A0 A1 D0.L char *NewGetFile ( struct FileInfo *, char *, ULONG ); FUNCTION Present a file requester from which the user may select a file or directory. Uses the user's preferred file requester (as set in Prefs). INPUTS fileinfo -- pointer to a FileInfo structure, describing how to open the file requester. You should fill in the following fields (do not touch any others): Dir: Directory where file requester should open. File: Default filename. Pattern: Filename pattern. Screen: Pointer to a custom screen on which to open. title -- title of the file requester. flags -- various flags for the file requester. FI_SAVE: Set when this requester is a save action. FI_DIRONLY: Only allow selection of a directory. FI_SCREEN: Force requester to open on the screen specified by FileInfo.Screen. RESULTS file -- complete path to filename chosen by the user if successful, or FALSE on failure. The FileInfo structure will also be updated to reflect the user's selection. EXAMPLE NOTES BUGS SEE ALSO scan.library/NumberRequest scan.library/NumberRequest NAME NumberRequest -- Present an integer gadget requester to the user. SYNOPSIS result = NumberRequest ( title, low, high, initial ); D0.L A0 D0.L D1.L D2.L LONG NumberRequest ( char *, LONG, LONG, LONG ); FUNCTION Display a requester containing a numeric integer gadget to the user. The user must enter a value or cancel before this function will return. INPUTS title -- Title of the requester. low -- Lowest value that can be selected with the slider (THIS IS CURRENTLY IGNORED except to determine cancelled values). high -- Highest value that can be selected with the slider (THIS IS CURRENTLY IGNORED). initial -- Initial value of the slider. RESULTS result -- value selected by the user. If the value is less than the lowest possible value, then the user cancelled the requester. EXAMPLE value = NumberRequest("Pick a number:", -10, 10, 0); if (value < -10) Errorf("Hey, you can't cancel me!"); NOTES BUGS SEE ALSO scan.library/ObtainBuffer NAME ObtainBuffer - Get a pointer to an image Buffer. SYNOPSIS buffer = ObtainBuffer ( which ); D0.L D0.L struct Buffer *ObtainBuffer ( int ); FUNCTION Returns a pointer to one of the image buffers in use within ImageFX. You should ALWAYS use this function to get at these buffers, as there is special initialization when the buffer is actually maintained on disk. INPUTS which -- Which buffer to get: 0 = Main buffer 1 = Swap buffer 2 = Alpha channel 3 = Undo buffer 4 = Brush buffer RESULT buffer -- A pointer to the Buffer or NULL if it could not be obtained for some reason. A typical reason for failure is that the given buffer does not exist. EXAMPLE NOTES You don't get a copy of the buffer, you get the actual pointer to the actual buffer, so be careful which fields you play with. A lot of the fields in the Buffer structure are for internal use only. Currently, two tasks can ObtainBuffer() the same buffer and be successful. This may change in the future. For now, try not to nest your ObtainBuffer()/ReleaseBuffer() calls. Remember to ReleaseBuffer() the buffer when you are done. BUGS None known. SEE ALSO scan.library/ReleaseBuffer,scan/buf.h scan.library/ParseCommand scan.library/ParseCommand NAME ParseCommand -- Parse an ImageFX command string. SYNOPSIS result = ParseCommand ( commandstring, message ); D0.L A0 A1 int ParseCommand ( char *, struct RexxMsg * ); FUNCTION Passes a string of commands to ImageFX for it to execute. This function does not return until the commands are completed (or aborted). The string may contain more than one command if each is separated by a semi-colon (;). INPUTS commandstring -- pointer to string of commands to execute. message -- invoking Arexx message, used to set result codes. You should pass NULL. RESULTS result -- result code from the commands, 0 for success or non-zero on failure. EXAMPLE ParseCommand("Negative; Swap; Color2Grey Luma", NULL); NOTES See the ImageFX manual chapter on Arexx commands for details of the commands that ImageFX understands. BUGS SEE ALSO scan.library/PutBufLine NAME PutBufLine - Restore last scanline read to a Buffer. SYNOPSIS success = PutBufLine ( buffer ); D0.L A0 int PutBufLine ( struct Buffer *buffer ); FUNCTION Restores to the given buffer the last scanline read with the GetBufLine() function. This function must be called if any changes are made to the scanline. You *MUST* call GetBufLine() before calling this function. INPUTS buffer -- Pointer to a Buffer structure as returned by ObtainBuffer(). RESULT success -- Non-zero if successful. EXAMPLE buffer = ObtainBuffer(0); if (buffer) { for (row = 0; row < buffer->Height; row++) { GetBufLine (buffer, &red, &grn, &blu, row); /* make some changes to the data */ PutBufLine (buffer); } ReleaseBuffer (buffer); } NOTES Not calling this function after making changes to a scanline will only become apparent when working on disk buffers. PAY ATTENTION TO THE RETURN VALUE!! Failing to gracefully handle a PutBufLine failure can cause serious problems. BUGS SEE ALSO scan.library/GetBufLine scan.library/PutBufLines scan.library/PutBufLines NAME PutBufLines -- Restore multiple scanlines to a buffer. SYNOPSIS success = PutBufLines ( buffer, topedge, rows ); D0.L A0 D0.L D1.L int PutBufLines ( struct Buffer *buffer, short topedge, short rows ); FUNCTION Restore the last batch of scanlines retreived with GetBufLines(). The scanline data may be replaced anywhere in the image, but it is generally a good idea to put it back where it came from. INPUTS buffer -- buffer to replace data into (must be the same as where it came from). topedge -- topedge location of where to restore the data (-1 means restore it where it came from). rows -- number of rows of data to restore (-1 means restore the same amount that was gotten). RESULTS success -- non-zero if successful, zero on failure. EXAMPLE NOTES BUGS SEE ALSO scan.library/GetBufLines scan.library/PutNewBufLine NAME PutNewBufLine - Store new image data into a buffer scanline. SYNOPSIS success = PutNewBufLine ( buffer, reddata, grndata, bludata, row ); D0.L A0 A1 A2 A3 D0.W int PutNewBufLine ( struct Buffer *, UBYTE *, UBYTE *, UBYTE *, short ); FUNCTION Stores image data into a buffer at any arbitrary scanline. You do NOT need to call GetBufLine() beforehand. The image data is copied, so you don't need to hold onto the data. INPUTS buffer -- Buffer structure as returned by ObtainBuffer(). reddata -- Pointer to Red image data. grndata -- Pointer to Green image data. bludata -- Pointer to Blue image data. row -- Scanline to store the data, starting from 0. RESULT success -- Non-zero if successful. EXAMPLE buffer = ObtainBuffer(0); if (buffer) { for (row = 0; row < buffer->Height; row += 4) { /* build a scanline of data */ PutNewBufLine (buffer, red, grn, blu, row); } ReleaseBuffer (buffer); } NOTES This function can only fail if the buffer is maintained on disk and memory could not be obtained to swap the relavant page into memory. When storing to a greyscale buffer, the Red pointer should point to the greyscale data. The other two pointers are ignored. PAY ATTENTION TO THE RETURN VALUE!! Failing to gracefully handle a PutNewBufLine failure can cause serious problems. BUGS SEE ALSO scan.library/GetBufLine,scan.library/PutBufLine scan.library/ReadBuffer scan.library/ReadBuffer NAME ReadBuffer -- Attempt to read an image file from disk. SYNOPSIS buffer = ReadBuffer ( filename, args ); D0.L A0 A1 struct Buffer *ReadBuffer ( char *filename, char *args ); FUNCTION Read image data from a disk file into an ImageFX Buffer structure. ImageFX will automatically figure out the file format and call the appropriate loader. INPUTS filename -- filename of image file to read. args -- argument string to be passed to the loader module that gets called (eg. could be used to specify a frame number for an animation loader). RESULTS buffer -- pointer to a properly filled-in Buffer structure, which can be used in any future operation. EXAMPLE NOTES Remember to KillBuffer() the buffer when you're done with it! BUGS SEE ALSO scan.library/RedrawArea scan.library/RedrawArea NAME RedrawArea -- Redraw a portion of the main image buffer. SYNOPSIS RedrawArea ( left, top, right, bottom ); D0.L D1.L D2.L D3.L void RedrawArea ( int, int, int, int ); FUNCTION Redraw only a portion of the current ImageFX main buffer. If redrawing has been disabled (with the "Redraw Off" command), no update will take place, but the screen will be refreshed when redraw is turned back on. You should call this or the RedrawFull() function after you have made a modification to an image buffer. INPUTS left, top -- upper left corner of the area you want to redraw, measured in pixels. right, bottom -- bottom right corner of the area you want to redraw, measured in pixels. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/RedrawFull scan.library/RedrawFull NAME RedrawFull -- Redraw main image buffer. SYNOPSIS RedrawFull (); void RedrawFull ( void ); FUNCTION Redraw the current ImageFX main buffer. If redrawing has been disabled (with the "Redraw Off" command), no update will take place, but the screen will be refreshed when redraw is turned back on. You should call this or the RedrawArea() function after you have made a modification to an image buffer. INPUTS None. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/RedrawArea scan.library/ReleaseBuffer NAME ReleaseBuffer - Release a Buffer after you're finished. SYNOPSIS ReleaseBuffer ( buffer ); A0 void ReleaseBuffer ( struct Buffer * ); FUNCTION Releases a Buffer obtained with ObtainBuffer(), doing any cleanup necessary. You should ALWAYS call this function when you are done with the Buffer, as there is special cleanup involved if the buffer is maintained on disk. INPUTS buffer -- Pointer to a Buffer structure obtained with the ObtainBuffer() structure. RESULT None. EXAMPLE NOTES BUGS SEE ALSO scan.library/ObtainBuffer,scan/buf.h scan.library/ReplaceBuffer scan.library/ReplaceBuffer NAME ReplaceBuffer -- Replace the contents of one buffer with another. SYNOPSIS ReplaceBuffer ( oldBuf, newBuf ); A0 A1 void ReplaceBuffer ( struct Buffer *, struct Buffer * ); FUNCTION Replaces the image data of the old buffer with the image data of the new buffer. The new buffer is then freed. INPUTS oldBuf -- pointer to Buffer to replace. newBuf -- pointer to Buffer with the image data that is to replace the old buffer. This buffer will be freed when the function returns. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/SaveBrush scan.library/SaveBrush NAME SaveBrush -- Save a Buffer structure to disk. SYNOPSIS success = SaveBrush ( buffer, filename, format, args ); D0.L A0 A1 A2 A3 BOOL SaveBrush ( struct Buffer *buffer, char *filename, char *format, char *args ); FUNCTION Save the image data of a Buffer structure to disk using a specified file format. ImageFX will load and call the appropriate saver module for the file format you specify. INPUTS buffer -- properly initialized Buffer structure to be saved. filename -- filename where image is stored. format -- file format to save in (eg. "ILBM", "ANIM", etc.). args -- argument string to be passed to the saver module that is called (eg. could be used to specify compression options). RESULTS success -- TRUE if the save was successful, or FALSE if it was not. EXAMPLE NOTES Yes, I know the function *should* be called SaveBuffer... But for various convoluted and not entirely valid reasons, it's still called SaveBrush. BUGS SEE ALSO scan.library/SaveMapped scan.library/SaveMapped NAME SaveMapped -- Save a colormapped image to disk. SYNOPSIS success = SaveMapped ( filename, format, image, args ); D0.L A0 A1 A2 A3 BOOL SaveMapped ( char *filenae, char *format, struct MappedImage *image, char *args ); FUNCTION Save a colormapped (eg. bitmap) image to disk using a specified file format. This is used to save rendered images. INPUTS filename -- name of file to save to. format -- file format name (eg. "ILBM", "ANIM", etc.). image -- pointer to a valid MappedImage structure. The following fields should be filled in: Width width of image in pixels. Height height of image in pixels. BitMap pointer to image's BitMap (the bitmap need not be in chip RAM). Palette.Depth depth of image (same as BitMap->Depth) Palette.Count count of colors used in the image (usually a power of two, but not required). Palette.Table pointer to RGB triplets of palette data. Modes viewmode of the image (if known). AspectX,AspectY horizontal and vertical aspect ratio of the image. args -- argument string to be passed to the saver module that is called. RESULTS success -- TRUE if the save was successful, or FALSE if something went wrong. EXAMPLE NOTES Note the argument order is NOT the same as SaveBrush. BUGS SEE ALSO scan/loadsave.h scan.library/SaveUndo scan.library/SaveUndo NAME SaveUndo -- Save an area of a buffer to the undo buffer. SYNOPSIS continue = SaveUndo ( buffer, left, top, width, height ); D0.L A0 D0.W D1.W D2.W D3.W BOOL SaveUndo ( struct Buffer *, short, short, short, short ); FUNCTION Stores a copy of the selected area of the buffer in the undo buffer. The previous contents of the undo buffer are lost. Only enough memory to hold the requested area is allocated for the undo buffer, to keep memory useage to a minimum. Always use this function if you are about to permanently alter ImageFX's main buffer, to give the user a chance to change his mind. INPUTS buffer -- pointer to Buffer from which to save the data. This will usually be either the main buffer or a brush. left, top -- upper left pixel coordinate of the area to save, starting from 0,0 at the upper left of the image. width, height -- pixel size of the area to save. RESULTS continue -- if there is not enough memory to save an undo buffer, the user will be asked if he would like to continue without one. The results of that request are returned here. TRUE means either there was enough memory or the user wants to continue, FALSE means the operation should be terminated. EXAMPLE if (buf = ObtainBuffer(0)) { if (SaveUndo(buf, 0, 0, buf->Width, buf->Height)) { /* do something to entire image */ } ReleaseBuffer(buf); } NOTES BUGS SEE ALSO scan.library/SetError NAME SetError - Set secondary error code. SYNOPSIS SetError ( errorcode ) D0.L void SetError ( ULONG ); FUNCTION Sets the secondary error code upon failure. Normally, functions simply return a TRUE or FALSE for success or failure. On failure, a person can look to the secondary error code to find more information about why a particular function failed. This presumes that the failing function puts some meaningful information in the secondary error code. INPUTS errorcode -- A code describing an error condition. Use the codes defined in "scan/errors.h". The ERR_UserCancel code will not generate a requester on failure, all others will. RESULT None. EXAMPLE NOTES BUGS SEE ALSO scan/errors.h scan.library/ShowPanel scan.library/ShowPanel NAME ShowPanel -- Bring the the menu screen to the front. SYNOPSIS ShowPanel () void ShowPanel ( void ); FUNCTION Bring the menu screen ("panel") to the front, if it is not already visible. You should always use this function instead of ScreenToFront(pScreen) so that the palette screen is handled properly. INPUTS RESULTS EXAMPLE NOTES BUGS SEE ALSO scan.library/HidePanel,scan.library/TogglePanel scan.library/ShowStatus NAME ShowStatus -- display buffer information on ImageFX menu. SYNOPSIS ShowStatus ( buffer ) A0 void ShowStatus ( struct Buffer * ) FUNCTION Updates the Image Scan information display (which shows the name of the current image and its width and height), updates the mode indicators and the channel gadgets. INPUTS buffer -- The buffer from which to get all the information to display. If NULL, then the current main buffer information will be used. RESULT None. EXAMPLE NOTES The main purpose for this is for Loaders to display the width/height/etc. of the file they are loading while decoding the file, so the user knows what he is loading. BUGS SEE ALSO scan.library/StringRequest scan.library/StringRequest NAME StringRequest -- Present a string gadget requester to the user. SYNOPSIS result = StringRequest ( title, initial ); D0.L A0 A1 char *StringRequest ( char *, char * ); FUNCTION Displays a string gadget requester where the user may enter a text string. The function does not return until the user enters a string or cancels. INPUTS title -- Title for the requester. initial -- Initial contents of the string gadget, may be NULL. RESULTS result -- pointer to the string the user entered or NULL if the user cancels the requester. You should make a copy of the string as soon as possible, because the next call to StringRequest() will destroy it. EXAMPLE NOTES BUGS SEE ALSO scan.library/TogglePanel scan.library/TogglePanel NAME TogglePanel -- Toggle the visibility of the menu screen. SYNOPSIS TogglePanel () void TogglePanel ( void ); FUNCTION Toggles the menu screen ("panel") in front or back of the other screens. This is what happens in response to a right mouse button click. INPUTS None. RESULTS None. EXAMPLE NOTES BUGS SEE ALSO scan.library/HidePanel,scan.library/ShowPanel scan.library/VBoolRequest scan.library/VBoolRequest NAME VBoolRequest -- Present boolean Okay/Cancel requester to user. BoolRequest -- varargs stub to VBoolRequest. SYNOPSIS result = VBoolRequest ( title, arglist ); D0.L A0 A1 BOOL VBoolRequest ( char *, ULONG * ); result = BoolRequest ( title, ... ); BOOL BoolRequest ( char *, ... ); FUNCTION Display a boolean Okay/Cancel requester to the user. The function does not return until the user presses either the Okay or Cancel gadgets. INPUTS title -- Title of the requester. Can contain printf-style formatting information. arglist -- pointer to list of arguments used to format the title string. RESULTS result -- TRUE if user selected Okay, FALSE if he selected Cancel. EXAMPLE NOTES BoolRequest() is defined in "scan.lib". BUGS SEE ALSO scan.library/VErrorf NAME VErrorf -- Display generic error message to user. Errorf -- varargs stub to VErrorf(). SYNOPSIS VErrorf ( controlstring, arglistptr ) A0 A1 void VErrorf (char *, LONG * ); Errorf ( controlstring, firstArg, ... ); void Errorf ( char *, ... ); FUNCTION Displays a bit of text to the user as an error message. The function does not return until the user clicks the Okay gadget in the requester. INPUTS controlstring -- A printf()-style formatting string. arglistptr -- pointer to a longword array of arguments to be formatted for display. RESULT None. EXAMPLE Errorf ("Your %ls didn't work on attempt #%ld!", bean_string, attempt_number); NOTES Errorf() is defined in "scan.lib". BUGS SEE ALSO scan.library/Error scan.library/VInfoRequest scan.library/VInfoRequest NAME VInfoRequest -- Display informational requester. InfoRequest -- varargs stub to VInfoRequest. SYNOPSIS VInfoRequest ( controlstring, arglistptr ) A0 A1 void VInfoRequest (char *, ULONG * ); InfoRequest ( controlstring, firstArg, ... ); void InfoRequest ( char *, ... ); FUNCTION Display a simple 1-line informational requester. The user must select the Okay gadget to proceed. INPUTS controlstring -- A printf()-style formatting string. arglistptr -- pointer to a longword array of arguments to be formatted for display. RESULTS None. EXAMPLE NOTES InfoRequest() is defined in "scan.lib". BUGS SEE ALSO scan.library/zzzzzz (That's so my autodoc-insertion macro works properly...)